Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d3 / ws5macro.arc / WSS.DOC < prev next >

Wrap

Text File | 1991-01-10 | 27.2 KB | 736 lines

================================================================= WSS: WORDSTAR SHORTHAND COMPILER AND DECOMPILER A Toolkit for Editing WordStar and NewWord Shorthand Macros With Optional Support for 25 NEW Shorthand Characters * * * Version 1.1 17 March 1988 * * * Programs Copyright 1989 by GARY M. GIBSON CompuServe User I.D.: 76616,3643 Documentation Copyright 1989 by ROBERT J. SAWYER and GARY M. GIBSON All Rights Reserved =================================================================== INTRODUCTION ============ The package consists of two MS-DOS programs, WSSC.EXE and WSSD.EXE which allow you to compile and decompile the Shorthand macro storage files used by WordStar and NewWord. They also allow you to optionally use up to 25 additional Shorthand characters besides the traditional 0 through 9 and A through Z. To install WSS, copy the files in this package to your WordStar working disk or subdirectory. SHORTHAND ========= The following MicroPro and Roxxolid word-processing programs all have essentially the same limited macro facility called "Shorthand." WordStar Professional Release 5.5 WordStar Professional Release 5 WordStar Professional Release 4 WordStar, CP/M Edition, Release 4 NewWord 3 MS-DOS NewWord 2 MS-DOS NewWord 2 CP/M These programs all store their macros in files with exactly the same format. For all versions of WordStar, the storage file is called WSSHORT.OVR by default; for NewWord, it's NWSHORT.OVR. These filenames can be changed using the appropriate installation program (WSCHANGE for WordStar; NWCHANGE for NewWord) at menu C (Computer), D (WordStar/NewWord's Files), or directly at user-area label SVFILE. If you are using WordStar 5 or greater and you have WSEX: The WordStar Extender (available from Library 13 of the CompuServe WordStar Forum in file WSEX.ARC), you can also specify on the command line a Shorthand filename other than the default by using the /FS option. Using the Shorthand feature of WordStar and NewWord, you can build a WSSHORT.OVR or NWSHORT.OVR file containing up to 36 user-defined Shorthand macros. They will be stored in alphanumeric order from 0 through 9 and A through Z. Using WSS, you can add up to 25 more characters, and these, too, are stored in the standard ASCII collating sequence. The file format for WSSHORT.OVR and NWSHORT.OVR, provided by provided by Peter Mierau, principal author of WordStar 4 and 5 and all versions of NewWord, is as follows: Byte Shorthand character Word Size of macro description for menu (X) Word Size of macro keystrokes (Y) X bytes Description for menu Y bytes Macro keystrokes All of the user-defined macros are packed together one right after another. They are terminated with a zero byte. The predefined macros (such as @ for today's date or = for the result from the last ^QM or ^KM math calculation) are NOT stored in the WSSHORT.OVR or NWSHORT.OVR file and may not be changed with WordStar, NewWord, or WSS. Although the file format for WSSHORT.OVR or NWSHORT.OVR is identical in all MS-DOS and CP/M versions, because of changes in the way WordStar 5 works -- particularly its use of dialogue boxes -- some macros created under WordStar 4 or NewWord will require editing before they will execute properly under WordStar 5. WSSD and WSSC ============= WordStar and NewWord do allow you to create and edit macros in the Shorthand dialogue box. However, editing is extremely limited: cursor movements are confined to the basic one-key editing diamond (no ^Q commands), typing is always in insert mode, and no block commands are allowed. Also, macros that are longer than the "Definition?" field in the dialogue box are very awkward to deal with, requiring you to enter the last part of the macro first, then cursor back to the beginning of field and enter the first part. Further, WordStar and NewWord will ONLY allow you to edit the 36 officially-sanctioned user-defined Shorthand characters. You must use WSS to edit the additional 25 Shorthand characters if you choose to use them. WSSD is the WordStar Shorthand Decompiler. It will scan your WSSHORT.OVR or NWSHORT.OVR file and produce a plain ASCII text file containing your Shorthand macros in a format you can edit easily with WordStar's or NewWord's non-document mode (or another ASCII editor). WSSC is the WordStar Shorthand Compiler. It will take the ASCII file after you've finished editing it and make a new WSSHORT.OVR or NWSHORT.OVR file from it. COMMAND-LINE SWITCHES ===================== WSSC accepts a number of command line options which may appear anywhere on the line, separated from each other and from file specifications by one or more blanks. Each option must start with a slash (/) or hyphen (-). The options are all switches. An option switch is set by specifying the option itself or with a trailing plus sign (+). The option switch is cleared by a trailing hyphen (-). Options are identified by the letter following the slash or dash; letter case doesn't matter. Any number of letters and/or digits may appear after the letter, if desired, to make a more meaningful option name. You can use these command-line switches in batch files, if you like. The WSSC command-line switches are: /A[+|-] Additional Shorthand characters allowed, meaning you can use up to 25 new Shorthand characters, as discussed below, for a total of 61 Shorthand character. Default is /A- (off), which means you can only use the 36 characters 0 through 9 and A through Z. If an additional character is used as a Shorthand macro name and the /A option has not been specified (or it has been disabled via /A-), an error message is given and no compiled Shorthand file will be produced. /Q[+|-] Quiet mode. Default is /Q- (off). If the /Quiet option is not specified, WSSC displays informational messages at the end of a successful compilation. If this option is turned on, WSSC minimizes the number of informational messages it generates during and after the compilation process. /W[+|-] Warning messages displayed. Default is /W+ (on). If this option is turned off, WSSC will only display error messages, never warnings. If it is on, each additional Shorthand character definition will produce a warning message, but compilation will proceed. ADDITIONAL SHORTHAND CHARACTERS =============================== WSS allows you to define up to 25 additional Shorthand characters. To compile them, you must use the /A+ WSSC command-line switch discussed above. Starting at the upper left of a 101-key keyboard and moving to the lower right, these characters are: Unshifted: ` open single quote characters: - hyphen (or minus) [ left square bracket ] right square bracket \ backslash ' apostrophe (or close single quote) , comma . period / slash Shifted ~ tilde characters: % percent ^ caret & ampersand ( left parenthesis ) right parenthesis _ underscore { left brace } right brace | pipe (or vertical line) : colon " double quote (or inch) < less than (or left angle bracket) > greater than (or right angle bracket) Numeric-keypad * asterisk characters: + plus (For the numeric-keypad characters, you can also use the shifted version: Shift-8 for asterisk and Shift-= for plus.) Note that these additional Shorthand characters are not supported by MicroPro or Roxxolid. They function correctly in all WordStar 4 and 5 releases and in NewWord 3, but they may not work with future versions of WordStar. Given that MicroPro already uses several characters (including @, #, and =) to designate special built-in Shorthand macro functions, some of the 25 additional characters may become unavailable for redefining in WordStar releases. Note, too, that although you can execute the defined functions in WordStar or NewWord, you CANNOT define or change the definitions for these characters with those programs. You must define them in a WSSC-compatible ASCII file, as described below. If you are using a 25-line screen, the WordStar or NewWord Shorthand Menu, which lists the names of defined Shorthand characters, can only show a maximum of 45 macro names (three columns of 15 names), despite the fact that a total of 61 may now be defined via WSS. If you are using at least a 31-line screen display (perhaps with an EGA, VGA, or, with WSEX, Hercules RamFont card), you will see all the macro names. With any screen dimensions, you can always scroll through the whole list on the Shorthand definition screen: Issue <Esc>? to bring up that screen, and then scroll the display with ^Z and ^W. Remember, though, you can only view the additional Shorthand characters from this display -- you cannot use it to change their definitions. USING WSS ========= The best way to learn these program is to try them. If you want to perform major surgery on your Shorthand overlay file WSSHORT.OVR, enter this command at the system prompt: WSSD wsshort WSSHORT.OVR must be in the current directory. WSSD will produce an ASCII file, WSSHORT.SHD, which you can edit in non-document mode, a process described in detail below. When you have the macros the way you want them to be, you can compile the *.SHD file back into a Shorthand overlay compatible with WordStar or NewWord by issuing this command: WSSC wsshort Note: This will overwrite the old WSSHORT.OVR with the new. To avoid this, both WSSC and WSSD allow a second filename, with optional extension, to designate the output file. So if you enter: WSSC wsshort updated WSSC will create UPDATED.OVR. You can test the macros in UPDATED.OVR by using WSEX's /FS switch, or by using WSCHANGE or NWCHANGE to change the default Shorthand filename to UPDATED.OVR. In summary, the command-line formats are: To decompile: WSSD [switches] shrthand[.OVR] [source[.SHD]] To compile: WSSC [switches] source[.SHD] [shrthand.OVR]] Information in square brackets is optional. EDITING A DECOMPILED SHORTHAND OVERLAY ====================================== A decompiled Shorthand file (*.SHD) is an ASCII text file containing two lines for each Shorthand macro you have defined. (Actually, you don't have to work on a decompiled Shorthand file. As long as you adhere to the format described here, you can build your *.SHD from scratch in WordStar or NewWord's non-document mode.) The lines in a decompiled Shorthand file should have the following format: Line 1: Shorthand-character Shorthand-description Line 2: Shorthand-definition The lines are shown here indented (as created by WSSD) but any number (including zero) of blanks or horizontal tabs (ASCII HT) may precede or follow any item. The components of a definition line pair are as follows: Shorthand-character A valid WordStar or NewWord Shorthand definition character (0-9, A-Z) in uppercase or lowercase, or one of the 25 WSS additional Shorthand characters. This is required. Shorthand-description Optional text to describe the use of the macro. Begins with the first non-blank/ non-Tab after the Shorthand-character and ends with the last non-blank/non-Tab on the line. May be blank. See below for the details on character coding. Shorthand-definition Optional text defining the macro. If present, the text *must* be enclosed in quotation marks ("----"). To make a null definition, so the macro will appear on the Shorthand menu without doing anything, simply put two consecutive quotation marks on this line: "". The Shorthand-description and Shorthand-definition text may contain any printable ASCII character. If you enter a character from the IBM extended character set, either with WordStar or another editor, WSSC will compile it properly. However, decompiled files produced by WSSD will show extended characters as their low-order ASCII equivalent. (Version 1.0 of WSSD placed ^[ and ^\ (caret, left square bracket; caret, backslash) fences around the decompiled extended characters. Recompiling this format with WSSC is still supported, so you can use your .SHD files created with WSS 1.0 without alteration.) The following character pairs must be used to enter certain characters: ^c Any valid control character in standard ASCII notation typed as a caret (^) followed by the character: ^A through ^Z in either uppercase or lowercase, or ^@, ^[, ^\, ^], ^^, or ^_. Note that to enter the character WordStar and NewWord call ^6, you must type it as two carets, ^^. \^ Forces a caret (^) character to be included. \" Forces a quote (") character to be included. This is not really necessary for the Shorthand-description, but it is supported there as well for consistency. \\ Forces a backslash (\) character to be included. You can put any number of blank line or comment lines between definition pairs. However, comment lines must begin with semicolon (;) characters, like this: ; this is a comment line. (It's because we use the semicolon this way that WSS does not allow it as a Shorthand character.) When WSSD creates a file, it automatically adds comment lines at the top identifying the filename and date and time of creation of the *.OVR file it decompiled. For example: ; Decompilation of WordStar Shorthand file C:\WS5\WSSHORT.OVR ; Shorthand overlay file was created on 17 Mar 1989 at 5:00pm Feel free to edit or delete these lines if you like. No WSSC source input lines can exceed 255 characters in length. Warning: if you exceed this length, the line is truncated WITHOUT an error message being produced. Note, too, that the longest Shorthand-description that will fit in the Shorthand Menu display without possibly overwriting another description is 22 characters. (By the way, WSSD has no intrinsic output line length, so it can create lines longer than WSSC can handle on input. However, this would only occur if a Shorthand macro's description or definition text was very long indeed.) Normally, Shorthand definitions are stored in alphanumeric/ASCII-collating order, but you may have changed some of the Shorthand-character assignments with DEBUG or a similar tool (previously, the only way to rename a Shorthand macro). This causes them to be stored out of order. The decompiler, WSSD, compensates for this and always decompiles the definitions in alphanumeric/ASCII-collating order. However, the compiler, WSSC, will accept definitions in ANY order. This means you don't have to worry about maintaining the alphabetical sequence and you can group definitions by function in the *.SHD file for easy reading. If you happen to define the same Shorthand-character twice, the first definition is the one that is used. When WSSC is run, it will inform you of what has happened with a diagnostic message. If you have a formatting error in your edited file, WSSC will not produce a new Shorthand overlay. Instead, it will terminate with an error message. WSSC produces files that can be substantially smaller than those saved by WordStar or NewWord. Those programs sometimes save more than they need; WSSC never does (they will always save the number of 128-bytes records specified at HANMAX, described below, even if all that space has not been used). When compiling is finished, WSSC displays the name of the output (*.OVR) file and its size in bytes. MEMORY BUFFER FOR SHORTHAND CHARACTERS ====================================== When WordStar or NewWord is run, the macro storage file is loaded into a fixed-length buffer in RAM. If there isn't enough memory, it truncates to the last macro that will fit. The buffer size can be changed with WSCHANGE or NWCHANGE at menu C (Computer), C (Memory usage), or directly at user-area label HANMAX (ShortHANd MAXimum file size). HANMAX is sized in records of 128 bytes, so a value of 4 sets aside 512 bytes. Note that each defined Shorthand character takes up five bytes plus the number of characters in the description and definition lines. If you set HANMAX to zero, Shorthand is disabled and the <Esc> key will clear the screen instead of initiating the macro function. Note, too, that the Shorthand buffer is a subset of the editing buffer -- the more space you set aside for macros, the less space is available in RAM for holding your document before it spills over to disk. Unless you have specified the /Quiet option, WSSC will tell you how big a HANMAX setting you will require by displaying a message such as this after a successful compilation: WordStar Shorthand Compiler - Version 1.1 Copyright (C) 1989 by G Systems. All rights reserved. Your new C:\WS5\WSSHORT.OVR file is 315 bytes long. A minimum HANMAX setting of 3 is required to use it. With HANMAX set to that value, you will have 69 bytes free. The HANMAX value can be changed at WSCHANGE menu C,C. If you use WSEX: The WordStar Extender, version 1.1, to be available in Library 13 of the CompuServe WordStar Forum as soon as WordStar 5.5 is made public, this fixed-length RAM buffer will be sized automatically each time you run WordStar to accommodate whatever Shorthand file you try to load. THE SAMPLE FILES ================ Included in this package are two sample compiled Shorthand storage files, 36.OVR and 61.OVR. They can, of course, be decompiled with WSSD. 36.OVR contains the same definitions provided in the WSSHORT.OVR file distributed with WordStar 5.0. All the other regular Shorthand characters are defined as null values, for a total of 36 macros. 61.OVR also contains the same definitions provided in the WSSHORT.OVR file distributed with WordStar 5.0. All the other regular Shorthand characters and the 25 additional Shorthand characters are defined with null values, for a total of 61 macros. What good are 36.OVR and 61.OVR, you may ask? Well, suppose you aren't using any of the 25 additional Shorthand characters, and you have defined 28 of the 36 available Shorthand characters. Your Shorthand menu might look like this: 0 Previous Page 1 Next Page 2 Date & Time 3 Sans-Serif 10 4 Roman 10 5 Courier 10 6 Soften Return 8 Erase to EOF A Sort Ascending B Import Box C Center D Sort Descending F Show All Files G Go To Any Note H Letterhead I Insert Five Spaces J Open Journal K Kill *.BAK L Log to Root Dir M Memo N Novel P Previous Paragraph R Reformat From Top S Sincerely T Transpose Word V Center Vertically Y ^P-Yellow Z Zubenelgenubi Quickly now: which characters are currently undefined? Hard to tell, right? But if the undefined characters have null definitions, your Shorthand menu would look like this: 0 Previous Page 1 Next Page 2 Date & Time 3 Sans-Serif 10 4 Roman 10 5 Courier 10 6 Soften Return 7 8 Erase to EOF 9 A Sort Ascending B Import Box C Center D Sort Descending E F Show All Files G Go To Any Note H Letterhead I Insert Five Spaces J Open Journal K Kill *.BAK L Log to Root Dir M Memo N Novel O P Previous Paragraph Q R Reformat From Top S Sincerely T Transpose Word U V Center Vertically W X Y ^P-Yellow Z Zubenelgenubi You can see at a glance that 7, 9, E, O, Q, U, W, and X are available. Note, though, that defining unused characters with null values does make the Shorthand file bigger (by five bytes for each character with a null definition). WSSC MESSAGES ============= WSSC: Character "c" cannot define a Shorthand macro. Only the characters 0-9 and A-Z (either case) may be used to name Shorthand macros, or the 25 additional characters IF the /A switch has been used. You attempted to define a Shorthand macro using another character, c. WSSC: Compilation error(s), no output file created. This indicates that there was at least one Shorthand macro definition error during the compilation. No output file is written; any previous file of the same name still exists. WSSC: Duplicate definition of "c". The Shorthand macro "c" was previously defined in the input (*.SHD) file. The duplicate definition is ignored -- the one defined first in the input file is the only one that appears in the output file. WSSC: Error on line n: <text> The input file (*.SHD) contained an error on line 'n' which is described by the following message. The line itself is shown as 'text'. WSSC: Input file "filename" close error. The input (*.SHD) file could not be closed successfully. This usually indicates that memory has been corrupted in some way. It may indicate a bug in WSSC. WSSC: Input file "filename" not found. The input (*.SHD) file cannot be found in the current directory. WSSC: Input file "filename" read error. An error has occurred reading the input (*.SHD) file. WSSC: Invalid ^char sequence: ^c. A control character (^c) sequence had an invalid second character. Only letters (either case), the special characters @, [, \, ], and _, or the sequence \^ may follow a caret. WSSC: Last Shorthand definition is missing 2nd line. The input (*.SHD) file terminated after the first Shorthand definition line of a pair. WSSC: Missing character after last "\". A Shorthand definition line ended with a backslash. The "\" must be followed by at least one character. WSSC: Missing character after last "^". A Shorthand definition line ended with a caret. The "^" must be followed by at least one character. WSSC: No Shorthand macros defined. The input (*.SHD) file contained only blank lines, commentary, or erroneous Shorthand macro definitions. WSSC: Output file "filename" cannot be created. There are no available directory entries on disk or there is an existing file of the same name which has the read-only attribute set and cannot be overwritten. WSSC: Output file "filename" close error. The output (*.OVR) file could not be closed successfully. This usually indicates that memory has been corrupted in some way. It may indicate a bug in WSSC. The file may or may not actually exist on disk. WSSC: Output file "filename" write error; disk full? A write to the output (*.OVR) file was unsuccessful or incomplete. A common cause of this is not having enough room available on the disk to which you are writing. WSSC: Processing terminated. A previously described error has caused WSSC to terminate processing without creating a complete Shorthand overlay file. WSSC: Text must be enclosed in quotes ("---"). The definition of a Shorthand macro (on the second line of a definition line pair) must be enclosed in quotation marks. WSSD MESSAGES ============= WSSD: Input file "filename" close error. The input (*.SHD) file could not be closed successfully. This usually indicates that memory has been corrupted in some way. It may indicate a bug in WSSD. WSSD: Input file "filename" is not a WordStar Shorthand file. The input file you specified does not appear to be a WordStar or NewWord Shorthand file. Please check to ensure that you spelled the file's name correctly and, if so, that the file actually is recognized by WordStar as a Shorthand definition file. WSSD: Input file "filename" not found. The input (*.OVR) file cannot be found in the current directory. WSSD: Input file "filename" read error. An error has occurred reading the input (*.OVR) file. WSSD: Output file "filename" cannot be created. There are no available directory entries on disk or there is an existing file of the same name which has the read-only attribute set and cannot be overwritten. WSSD: Output file "filename" close error. The output (*.SHD) file could not be closed successfully. This usually indicates that memory has been corrupted in some way. It may indicate a bug in WSSD. The file may or may not actually exist on disk. WSSD: Output file "filename" write error; disk full? A write to the output (*.SHD) file was unsuccessful or incomplete. A common cause of this is not having enough room available on the disk you are writing to. WSSD: Processing terminated. A previously described error has caused WSSD to terminate processing without creating a complete Shorthand overlay file. # # # # #